CU Amiga Super CD-ROM 25

home *** CD-ROM | disk | FTP | other *** search

/ CU Amiga Super CD-ROM 25 / CU Amiga Magazine's Super CD-ROM 25 (1998)(EMAP Images)(GB)(Track 1 of 2)[!][issue 1998-08].iso / CUCD / Magazine / C_Tutorial / Part-13 / PatchLib / autodocs / patch.doc

Wrap

Text File | 1997-12-11 | 42.3 KB | 1,061 lines

TABLE OF CONTENTS patch.library/AddPatchNotifyA patch.library/CreatePatchProjectA patch.library/FindPatch patch.library/FindPatchTagsA patch.library/GetPatchA patch.library/InstallPatch patch.library/InstallPatchTagsA patch.library/PatchAlloc patch.library/PatchFreeVec patch.library/RemovePatch patch.library/RemovePatchProjectA patch.library/RemovePatchTagsA patch.library/RemPatchNotifyA patch.library/SetPatchA patch.library/SetPatchProjectA patch.library/WaitRemovePatch patch.library/AddPatchNotifyA patch.library/AddPatchNotifyA NAME AddPatchNotifyA -- Get messages, if a patch is changed. (V5) AddPatchNotify -- varargs stub for AddPatchNotifyA(). (V5) SYNOPSIS Error = AddPatchNotifyA( msgport, taglist ) D0 A0 A1 ULONG Error AddPatchNotifyA( struct MsgPort *, struct TagItem *); Error = AddPatchNotify( msgport, ...) ULONG Error AddPatchNotify( struct MsgPort *, ...); FUNCTION Patch.library will immediately start sending out PatchNotifyMessages (see patch.h) of PATCHNOTIFY_CLASS to the given message port, if a patch is added, removed or changed. pnm_Code contains PATCOD_xxx values to indicate the kind of change. For PATCOD_PatchInstalled and PATCOD_PatchChanged pnm_Object will contain a pointer to the corresponding patch structure. INPUTS msgport = pointer to msgport ready to receive messages or null for no action taglist = pointer to array of tags TAGS PATT_Priority (BYTE) - Optional priority for the notification request Normally only the priorities +5, 0, -5 should be used. RESULT Error = errorcode as defined in patch.h. PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. NOTES BUGS SEE ALSO RemPatchNotify(), patch.h patch.library/CreatePatchProjectA patch.library/CreatePatchProjectA NAME CreatePatchProjectA -- Create an instance of a patch project. (V4) CreatePatchProject -- varargs stub for CreatePatchProjectA(). (V4) SYNOPSIS project = CreatePatchProjectA( projectname, taglist ) D0 A0 A1 APTR CreatePatchProjectA( STRPTR, struct TagItem *); project = CreatePatchProject( projectname, ...) APTR CreatePatchProject( STRPTR, ...); FUNCTION Create an instance of a patch project. This instance may be used to manipulate or remove patches belonging to one project (or program) with one function call. The projectname will be copied into an internal buffer. INPUTS projectname = pointer to name of the patch project taglist = pointer to array of tags TAGS none defined yet RESULT project = pointer to patch projects private structure or null on failure NOTES BUGS SEE ALSO RemovePatchProject(), InstallPatchTags(), patch.h patch.library/FindPatch patch.library/FindPatch NAME FindPatch -- find a patch structure with a given name. SYNOPSIS patch = FindPatch( name ) D0 A0 struct Patch *FindPatch( STRPTR ); FUNCTION This function will search the patch.library lists for a patch structure with the given name. The first patch matching this name will be returned. This function exists only for historic reasons. It will internally be routed to FindPatchTags(). INPUTS name = Name of the patch structure to find RESULT patch = a pointer to the patch structure with the same name else NULL to indicate that the string was not found. NOTES If your task is not the owner of the patch, the pointer is only valid as long as the system is in forbid(). From V2 on you may also lock the patch.library semaphore before calling this function. In this case a pointer to a patch structure is guaranteed to be valid, until you release the semaphore. The semaphore, however, should be kept locked only for short periods of time in order not to block other tasks. BUGS SEE ALSO InstallPatch(), RemovePatch(), patch.h patch.library/FindPatchTagsA patch.library/FindPatchTagsA NAME FindPatchTagsA -- find a patch structure with certain criteria. (V3) FindPatchTags -- varargs stub for FindPatchTagsA(). (V3) SYNOPSIS object = FindPatchTagsA( taglist ) D0 A0 APTR FindPatchTagsA( struct TagItem *); object = FindPatchTags( ...) APTR FindPatchTags( ...); FUNCTION This function will search the patch.library lists for a patch structure, that matches the criteria specified in the taglist. The first matching patch will be returned. INPUTS taglist = pointer to array of tags TAGS Specify only one of these at a time: PATT_PatchName (STRPTR) - Specifies that patch.library should search for the patch with the given name. PATT_ProjectName (V4) (STRPTR) - Specifies that patch.library should search for the project with the given name. PATT_NoCase (V4) (BOOL) - If specified with PATT_PatchName or PATT_ProjectName string-comparison will be case-independent. International characters are not respected with this version of patch.library. This may or may not change in the future. PATT_LastObject (V4) (APTR) - This tag allows to search for multiple matching objects. Simply specify the result of a previous call to FindPatchTags() to continue searching with this tag. You may also specify NULL to start searching the lists from the beginning. Keep in mind, that you must make sure, that the pointer is valid (see notes). RESULT object = a pointer to the object as requested within the taglist or NULL to indicate that no match was found. NOTES If your task is not the owner of the patch, the pointer is only valid as long as the system is in forbid(). You may also lock the patch.library semaphore before calling this function. In this case a pointer to a patch structure is guaranteed to be valid, until you release the semaphore. The semaphore, however, should be kept locked only for short periods of time in order not to block other tasks. patch.library/GetPatchA patch.library/GetPatchA NAME GetPatchA -- Returns certain attributes of a patch. (V3) GetPatch -- varargs stub for GetPatchA(). (V3) SYNOPSIS Result = GetPatchA( patch, taglist ) D0 A0 A1 ULONG Result GetPatchA( struct Patch *, struct TagItem *); Result = GetPatch( patch, ...) ULONG Result GetPatch( struct Patch *, ...); FUNCTION Returns certain attributes and lists connected to a patch (see TAGS). INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_Result2 (ULONG *) - An optional pointer to a longword, which will contain an errorcode as defined patch.h, when the function returns. Assembler programmers can get the same value from d1. Only one of the following tags may be specified at a time: PATT_PatchName (BOOL) - Return a pointer to a copy of the name of the patch in a null-terminated string. This pointer must be passed to PatchFreeVec(), if the string is no longer needed. Type of Result is STRPTR. PATT_TaskListType (BOOL) - Return the type of the internal TaskList Possible results: TL_TYPE_INCLUDE: all specified tasks will use the patchroutine, all others will ignore it. TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine, all others will use it. NULL: An error occurred (this includes the absence of a TaskList). Check the secondary errorcode for more information. Type of Result is ULONG. PATT_TaskList (BOOL) - Return a pointer to a taglist containing all tasknames, taskids or patterns attached to a patch. The tagitems are PATT_AddTaskName, PATT_AddTaskID or PATT_AddTaskPattern(new for V5). Unknown tags must be ignored. This pointer must be passed to PatchFreeVec(), if the tasklist is no longer needed. Type of Result is taglist. PATT_Disabled (V4) (BOOL) - Return a number representing the current disable nesting counter of a patch. Null means the patch is enabled and will be used, by any tasks using the library function. Type of Result is ULONG. PATT_UserData (V5) (BOOL) - Return userdata attached to a patch. Type of Result is ULONG. PATT_Priority (V5) (BOOL) - Return the priority of a patch. Type of Result is BYTE. PATT_Original (V6) (BOOL) - Return a pointer to the original function. Only possible, if patch was installed with PATT_Original Type of Result is (* )(). RESULT Result = Pointer or longword depending on specified tags. Possible errorcodes returned with PATT_Result2 or in register d1: PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). PATERR_NoTaskList No valid TaskList is attached to the patch. The SetPatchA() function with the PATT_CreateTaskList tag specified, must be called to allocate a TaskList. PATERR_PatchUnnamed The patch has no identification string attached to it. NOTES BUGS SEE ALSO InstallPatchTags(), PatchFreeVec(), patch.h, patchtags.h patch.library/InstallPatch patch.library/InstallPatch NAME InstallPatch -- Installs a patchroutine for library functions. SYNOPSIS patch = InstallPatch( newpatch ) D0 A0 struct Patch *InstallPatch( struct NewPatch * ); FUNCTION This function exists only for historic reasons. It will internally routed back to InstallPatchTags(). Because InstallPatchTags() has advanced features there is definitely no need to call this function at all. INPUTS newpatch = pointer to an instance of a NewPatch structure RESULT patch = pointer to a patch structure or NULL on failure NOTES BUGS SEE ALSO InstallPatchTags(), patchobsolete.h patch.library/InstallPatchTagsA patch.library/InstallPatchTagsA NAME InstallPatchTagsA -- Installs a patchcode for library functions. (V2) InstallPatchTags -- varargs stub for InstallPatchTagsA(). (V2) SYNOPSIS patch = InstallPatchTagsA( funcEntry, funcOffset, taglist ) D0 A0 D0 A1 struct Patch *InstallPatchTagsA( APTR, UWORD, struct TagItem * ); patch = InstallPatchTags( funcEntry, funcOffset, ...) struct Patch *InstallPatchTags( APTR, UWORD, ...); FUNCTION Adds a user provided routine to a library function. NEW for V3: An internal call to SetPatch() will be made. So all tags which are valid with SetPatch() may be specified in the taglist. INPUTS funcEntry = pointer to the entry of the function to add funcOffset = Library Offset Vector (LVO) of the function to patch taglist = pointer to array of tags TAGS PATT_LibraryName (STRPTR) - Specifies that you want to patch a library of the given name ( as in exec.library/OpenLibrary() ). Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_DeviceName (STRPTR) - Specifies that you want to patch a device of the given name ( as in exec.library/OpenDevice() ). Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_LibraryBase (struct Library *) Specifies that you want to patch a library, device or resource with the given base. You may get such a pointer by calling one of the following exec functions: OpenLibrary(), OpenDevice(), OpenResource() You may safely close this library, if InstallPatchTags() returns, because patch.library will increase the OpenCount to make sure, that the library won't be removed from the system as long as there are patches installed. V4: The OpenCount will not be increased, if the PatchSupervisor support program is active. Either PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be specified. PATT_LibVersion (ULONG) - Versionnumber for exec.library/OpenLibrary. Optional in conjunction with PATT_LibraryName. Should be specified, if a function is available only from a certain library version on. Default is NULL (any version). PATT_DevFlags (ULONG) - Flags for exec.library/OpenDevice(). Optional in conjunction with PATT_DeviceName. Default is NULL. PATT_DevUnit (ULONG) - Unit for exec.library/OpenDevice(). Optional in conjunction with PATT_DeviceName. Default is NULL. PATT_PatchName (STRPTR) - An optional pointer to a string, which can be used to search for a patch with FindPatch() or FindPatchTags(). The null-terminated string will be copied, so you may free its memory when InstallPatchTags() returns. The string should identify the program that installed the patch. Even though this tag is optional, the use of it is strongly encouraged, because without it certain future enhancements of the patch.library may not work (e.g.: saving of user-settings). PATT_Priority (BYTE) - Priority of the patch valid range: -127...+126 It indicates the sequence of patches, if more than one patch for a function is to be installed. The original code has a priority of 0. Priority: Meaning: >0: patch will be executed before the original <0: patch will be executed after the original =0: patch will be executed instead of the original (default) Normally only the priorities +5, 0, -5 should be used. PATT_NewCodeSize (ULONG) - Optional length of the patch code to be installed. If this field is set to the correct value the PC-RELATIVE patch code starting at funcEntry will be copied into an internal buffer. So it is possible to deallocate the patch code after InstallPatchTags() returned. PATT_Result2 (ULONG *) - An optional pointer to a longword, which will contain an errorcode as defined patch.h, when the function returns. Assembler programmers can get the same value from d1. PATT_ProjectID (APTR) (V4) - Optional pointer to a PatchProject as created by a CreatePatchProject() function call, indicating that the newly installed patch belongs to one project or program. If used together with the RemovePatchProject() function many patches can be removed with one function call. PATT_UseXResult (BOOL) (V5) - If this tag is set to TRUE, your patchcode MUST return a PatchXResult structure in d0. See PatchAlloc for more informations. PATT_Original *((* )()) (V6) - Pointer to a longword or NULL. If you specify this tag you indicate, that you want to call the original function from within your patchcode. You may get this pointer by specifying a pointer to a longword, which will be used in your patchcode to call the original function (e.g.: jsr LongWord). If you specify NULL with this tag you can get the pointer to the original function by a later call to GetPatch(). WARNING: Your patchcode must be ready to be called immediately, unless you also specify PATT_Disable,TRUE. So PATT_Original,NULL should always be paired with PATT_Disable,TRUE. Also note, that PATT_Priority MUST be > 0, if you specify this tag. For more tags see the description of SetPatch(). RESULT patch = pointer to a patch structure or NULL on failure Errorcodes returned with PATT_Result2, NPAT_Result2 or in register d1: Note that from V3 on errorcodes may be returned, even if patch is a valid pointer, indicating a failure in the internal SetPatch() call. Previous versions always set PATERR_Ok, if patch was a valid pointer. PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_OpenLib The operation failed, because the exec.library function OpenLibrary() failed. Check the Autodocs for more informations about OpenLibrary(). PATERR_OpenDev The operation failed, because the exec.library function OpenDevice() failed. Check the Autodocs for more informations about OpenDevice(). PATERR_FuncNotStd The library offset vector of the function to patch was not in format that patch-library can accept. Patch.library can handle the following formats: jmp xxxxxx moveq.l #xx,Dx bra.l xxxx (up to V5 only) moveq.l #xx,Dx bra.s xx (up to V5 only) Note that this is the type of error returned, if you are trying to patch a function that uses in-line code such as exec.library/GetCC() PATERR_InvalidTags An error occurred while parsing the specified Tags (e.g.: EITHER PATT_LibraryName, PATT_DeviceName or PATT_LibraryBase MUST be used) For more errorcodes see the description of SetPatch(). NOTES This function may implicitly call dos.library functions, so do not call it from tasks. BUGS Up to V4 it was not possible to pass pathnames with PATT_LibraryName or PATT_DeviceName (e.g.: "Work:libs/foo.library"). This has been fixed in V5. SEE ALSO RemovePatchTags(), RemovePatchProject(), SetPatch(), PatchAlloc(), patch.h, patchtags.h, exec.library/OpenLibrary(), exec.library/OpenDevice() patch.library/PatchAlloc patch.library/PatchAlloc NAME PatchAlloc -- Allocate and initialize structures (V5) SYNOPSIS structure = PatchAlloc(type) D0 APTR PatchAlloc(ULONG type); FUNCTION Allocate and initialize structures for use with patch.library. NOTE Call PatchFreeVec() to free the memory unless documented otherwise. INPUTS type = type of structure to allocate Currently defined types: PS_TYPE_XRESULT - Allocate a PatchXResult structure used in conjunction with the Extended-Result-System (See Example below) RESULT structure = pointer to a structure or NULL on failure EXAMPLE To add 30 ticks to the each dos.library/Delay() function your patchcode would look like this (in SAS/C): __asm __saveds struct PatchXResult *MyDelay(register __d1 ULONG ticks) { struct PatchXResult *xresult; ticks += 30; xresult = (struct PatchXResult *)PatchAlloc(PS_TYPE_XRESULT); if(xresult ) { xresult->pxr_RegD1 = ticks; xresult->pxr_RegPattern = PATREG_D1; } return(xresult); } SEE ALSO GetPatch(), PatchFreeVec(), patch.h patch.library/PatchFreeVec patch.library/PatchFreeVec NAME PatchFreeVec -- free patch.library structures (V3) SYNOPSIS PatchFreeVec(memoryBlock) A1 void PatchFreeVec(void *); FUNCTION Free memory and structures used by patch.library. The memory will be returned to the system pool from which it came. NOTE INPUTS memoryBlock - pointer to the memory block to free, or NULL. SEE ALSO GetPatch(), exec.library/FreeVec patch.library/RemovePatch patch.library/RemovePatch NAME RemovePatch -- Removes a patch installed by InstallPatch(). SYNOPSIS Error = RemovePatch( patch ) D0 A0 ULONG Error RemovePatch( struct Patch * ); FUNCTION This function is obsolete from V2 on, use RemovePatchTags() instead. It effectively calls the new function RemovePatchTags(patch, PATT_DelayedExpunge, FALSE, TAG_DONE) INPUTS patch = pointer to the patch structure or NULL for no action RESULT Error = errorcode as defined in patch.h. (for more information see RemovePatchTags() ) NOTES BUGS SEE ALSO RemovePatchTags(), patch.h patch.library/RemovePatchProjectA patch.library/RemovePatchProjectA NAME RemovePatchProjectA -- Remove all patches from the same project. (V4) RemovePatchProject -- varargs stub for RemovePatchProjectA(). (V4) SYNOPSIS Error = RemovePatchProjectA( project, taglist ) D0 A0 A1 ULONG Error RemovePatchProjectA( APTR, struct TagItem *); Error = RemovePatchProject( project, ...) ULONG Error RemovePatchProject( APTR, ...); FUNCTION Remove all patches from the given project. This function simplifies the way, patches can be removed: - All patches belonging to one project will be disabled - The function then waits (depending on PATT_Timeout) until the usagecounters of all patches become zero - Now all patches will be removed via RemovePatchTags() - If all patches are removed resources connected to the project will be deallocted You may call this function to cleanup a project, even if no patch was successfully installed for this project. INPUTS project = pointer to a patch project obtained via CreatePatchProject() taglist = pointer to array of tags TAGS same as RemovePatchTags() RESULT Error = errorcode as defined in patch.h. same as RemovePatchTags() NOTES Removing a patch routine can never be made absolutely safe. Although patch.library does anything possible to provide methods to minimize the chance of a crash, there will always be a slight chance. So minimize the number of install and remove operations. BUGS SEE ALSO CreatePatchProject(), InstallPatchTags(), RemovePatchTags(), patch.h, patchtags.h patch.library/RemovePatchTagsA patch.library/RemovePatchTagsA NAME RemovePatchTagsA -- Removes an installed patch. (V2) RemovePatchTags -- varargs stub for RemovePatchTagsA(). (V2) SYNOPSIS Error = RemovePatchTagsA( patch, taglist ) D0 A0 A1 ULONG Error RemovePatchTagsA( struct Patch *, struct TagItem *); Error = RemovePatchTags( patch, ...) ULONG Error RemovePatchTags( struct Patch *, ...); FUNCTION Removes a patch from a library function. All allocated resources for that specific patch will be deallocated. INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_TimeOut (ULONG) - The number of ticks (1/50 seconds) the function keeps trying to remove the patch, if another task is running in the patchcode. If the patch.library does not succeed in the given time the function will return PATERR_PatchInUse. Defaults to NULL, which means no retry. PATT_DelayedExpunge (BOOL) - If this tag is not set to FALSE and a non-patch.library patch was installed after the patch.library patch for a specific library function the specified patch will nevertheless be removed. BUT some resources will be kept allocated by patch.library (e.g.: the Library Offset Vector will not be restored to its old state). Patch.library will try to deallocate these resources automatically, if the system is getting low on memory or if a call to a patch.library function that removes or installs patches is made. The default is TRUE !!! RESULT Error = errorcode as defined in patch.h. PATERR_Ok Indicates success of the operation. PATERR_PatchInUse Indicates that some other task is using the installed function and the patch can't be removed. Your task may wait and try again later. PATERR_PatchInstalled Indicates that a patchcode has been installed for that function after your patch.library patch has been installed and your patch is the only patch.library patch for that function. If patch.library would remove your patch tasks would jump into deallocated memory Result: blinking borders. Never occurs, if you pass in the tag PATT_DelayedExpunge with TRUE. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). Also keep in mind that ln_Type must be PS_TYPE_USER. NOTES Removing a patch routine can never be made absolutely safe. Although patch.library does anything possible to provide methods to minimize the chance of a crash, there will always be a slight chance. So minimize the number of install and remove operations. This function may implicitly call dos.library functions, so do not call it from tasks. BUGS SEE ALSO InstallPatchTags(), RemovePatchProject(), patch.h, patchtags.h patch.library/RemPatchNotifyA patch.library/RemPatchNotifyA NAME RemPatchNotifyA -- Stop receiving messages, if a patch is changed. (V5) RemPatchNotify -- varargs stub for RemPatchNotifyA(). (V5) SYNOPSIS Error = RemPatchNotifyA( msgport, taglist ) D0 A0 A1 ULONG Error RemPatchNotifyA( struct MsgPort *, struct TagItem *); Error = RemPatchNotify( msgport, firsttag, ...) ULONG Error RemPatchNotify( struct MsgPort *, Tag, ...); FUNCTION Stop receiving notification requests for the given messageport. The messageport should have been used in a previous call to AddPatchNotify(). Before deallocating your MsgPort you must reply outstanding messages. INPUTS msgport = pointer to msgport or null for no action taglist = pointer to array of tags TAGS none defined yet RESULT Error = errorcode as defined in patch.h. PATERR_Ok Indicates success of the operation. NOTES BUGS SEE ALSO AddPatchNotify(), patch.h patch.library/SetPatchA patch.library/SetPatchA NAME SetPatchA -- Changes certain attributes of a patch. (V3) SetPatch -- varargs stub for SetPatchA(). (V3) SYNOPSIS Error = SetPatchA( patch, taglist ) D0 A0 A1 ULONG Error SetPatchA( struct Patch *, struct TagItem *); Error = SetPatch( patch, ...) ULONG Error SetPatch( struct Patch *, ...); FUNCTION Changes certain attributes of a patch (see TAGS). INPUTS patch = pointer to a patch structure or NULL for no action taglist = pointer to array of tags TAGS PATT_CreateTaskList (ULONG) - Create a TaskList of the given type: TL_TYPE_INCLUDE: all specified tasks will use the patchroutine, all others will ignore it. So if no Task is specified via PATT_AddTask... tags, the patchroutine will be used for NO tasks! TL_TYPE_EXCLUDE: all specified tasks will ignore the patchroutine, all others will use it. So if no Task is specified via PATT_AddTask... tags, the patchroutine will be used for ALL tasks! PATT_DeleteTaskList (BOOL) - Delete any existing TaskList This will return the patch to its default behaviour, which is to call the patchroutine for any task. It is not required to remove the TaskList, before you remove a patch, (via RemovePatchTags()) because this will automatically be done by patch.library. PATT_AddTaskID (struct Task *) - Add a task address to the patch TaskList. Patch.library takes care that one TaskID appears only once in the TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_AddTaskName (STRPTR) - Add a task of the given name to the patch TaskList. The string will be copied into an internal buffer. These tasknames are case-sensitive. Patch.library takes care that one TaskName appears only once in the TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_RemTaskID (struct Task *) - Remove a task address from the patch TaskList Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_RemTaskName (APTR) - Remove a task of the given name from the patch TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_Disabled (V4) (BOOL) - Enable (False) or disable (True) a patch. For disabling a patch a nesting counter is provided. In order to restore normal patch execution, the programmer must provide exactly one call to 'enable' for every 'disable'. If a patch is disabled this does not mean, that no task continues to use the patched code. It only makes sure, that no further tasks enter the patch code. If PATT_Disabled,TRUE is set with InstallPatchTags() the patch will not be called until explicitly enabled by a call to SetPatchTags(). PATT_AddRemoveHook (V4) (struct Hook *) - Add a Hook, which is called by patch.library whenever a patch is removed from memory. Neither the Hook structure nor the hookfunction are copied into internal memory. So freeing these structures must be accomplished by the hookfunction itself. It must also preserve all registers. The hookobject (Register A2) for this hook is the patch structure. For more information about hooks see utility/hooks.h, utility.library/CallHook() or the RKMs. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_RemRemoveHook (V4) (struct Hook *) - Remove a Hook installed with PATT_AddRemoveHook. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_UserData (V5) (ULONG) - Attach userdata to a patch. Use this tag only, if you are the owner (creator) of the patch. PATT_AddTaskPattern (V5) (STRPTR) - Add a pattern of tasknames to the patch TaskList. The pattern may contain dos wildcards. Patch.library takes care that one pattern appears only once in the TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. This tag only works with kickstart V37+. DO NOT USE this tag, if you patch one of the following dos-functions: MatchPattern() or MatchPatternNocase() PATT_RemTaskPattern (V5) (STRPTR) - Remove a taskpattern from the patch TaskList. Unlike many tags, you may specify this tag more than once in one taglist to add multiple tasks to the list. PATT_StackSize (V5) (ULONG) - Minimum stacksize (in bytes) your function requires. This value should be a multiple of 4 and more than 256. If a taskpattern (see PATT_AddtaskPattern) is active, at least 1500 Bytes should be specified. DO NOT USE this tag, if you patch one of the following exec-functions: FindTask(), AllocMem(), FreeMem() or StackSwap() You may specify zero to turn stack extension off. PATT_Priority (V5) (BYTE) - Priority of the patch valid range: -127...+126 It indicates the sequence of patches, if more than one patch for a function is installed. The original code has a priority of 0. Priority: Meaning: >0: patch will be executed before the original <0: patch will be executed after the original =0: patch will be executed instead of the original (default) Normally only the priorities +5, 0, -5 should be used. Changing the priority of an active patch is a difficult operation. It may fail with PATERR_PatchInUse. You MUST NOT change the priority of a patch in respect to the original function (see above). RESULT Error = errorcode as defined in patch.h. PATERR_Ok Indicates success of the operation. PATERR_OutOfMem Indicates that there was not enough memory to complete the operation. PATERR_PatchInUse Indicates that some other task is using the installed function and the priority of the patch can't be changed right now. Your task may wait and try again later. PATERR_InvalidHandle Indicates that the pointer to the patch passed to the function was not or is no longer valid. This might happen, if you pass a wrong pointer or you got the pointer via FindPatch() and another task has removed the patch before this task called RemovePatchTags(). PATERR_NoTaskList No valid TaskList is attached to the patch. The SetPatchA() function with the PATT_CreateTaskList tag specified, must be called to allocate a TaskList. PATERR_TaskListExists PATT_CreateTaskList was specified, but there already exists a TaskList. PATERR_InvalidTaskList PATT_CreateTaskList was specified with a wrong parameter. PATERR_KickTooOld PATT_AddTaskPattern was used on a system with Kickstart V36or lower. (No longer possible with patch.library V6+, as Kickstart V37+ is required.) PATERR_InvalidPattern PATT_AddTaskPattern was used with a string, which contained an invalid pattern. See dos.library ParsePattern() for more informations. PATERR_Restricted PATT_AddTaskPattern or PATT_StackSize was used for a forbidden function (see TAGS). NOTES Using the TaskList feature provided by this function will (by a huge amount in the case of PATT_AddTaskPattern) increase the stackusage of the patched function. See PATT_StackSize for a solution. BUGS SEE ALSO InstallPatchTags(), patch.h, patchtags.h, dos.library/ParsePatternNoCase(), dos.library/ParsePattern() patch.library/SetPatchProjectA patch.library/SetPatchProjectA NAME SetPatchProjectA -- Changes certain attributes of a project. (V5) SetPatchProject -- varargs stub for SetPatchProjectA(). (V5) SYNOPSIS Error = SetPatchProjectA( project, taglist ) D0 A0 A1 ULONG Error SetPatchProjectA( APTR, struct TagItem *); Error = SetPatchProject( project, ...) ULONG Error SetPatchProject( APTR, ...); FUNCTION Changes certain attributes of a group of patches belonging to one project. For now (V5) it mainly calls SetPatch() recursive for all patches belonging to the project. Certain project specific tags may be implemented later. INPUTS project = pointer to a patch project obtained via CreatePatchProject() or NULL for no action taglist = pointer to array of tags TAGS see SetPatch() for a list of valid tags. RESULT Error = errorcode as defined in patch.h. see SetPatch() for a list of errorcodes NOTES Currently (V5) SetPatchProject() stops changing patches, when any of the internal calls to SetPatch() return an error. Therefore when SetPatchProject() returns an error, some patches may have been changed and others not. BUGS SEE ALSO SetPatch(), patch.h, patchtags.h, CreatePatchProject() patch.library/WaitRemovePatch patch.library/WaitRemovePatch NAME WaitRemovePatch -- Waits until it is possible to remove a patch. SYNOPSIS Error = WaitRemovePatch( patch ) D0 A0 ULONG Error WaitRemovePatch( struct Patch * ); FUNCTION This function is obsolete from V2 on, use RemovePatchTags() instead. It effectively calls the new function RemovePatchTags(patch, PATT_TimeOut, 0x7fffffff, PATT_DelayedExpunge, FALSE, TAG_DONE) INPUTS patch = pointer to the patch structure or NULL for no action RESULT Error = errorcode as defined in patch.h. (for more information see RemovePatchTags() ) NOTES BUGS (?) This function will never return, if the patched library function crashed for some reason. SEE ALSO RemovePatchTags()